feat(2fa): trusted devices management UI and revoke endpoints - #160

ref https://app.clickup.com/t/86bc647cd (SDS idp-mfa.md 5.5 / 5.6)

Summary

Users could mark a device as trusted when completing a 2FA challenge, but had no way to see or revoke those devices: a lost or shared device kept bypassing the challenge until the cookie expired (30 days by default). This adds self-service listing and revocation, on the API and on the profile page.

Backend

New routes in the existing admin/api/v1 → users/me group (session-authenticated, ssl + auth):

• Listing: only non-revoked, non-expired devices of the caller. UserTrustedDeviceSerializer returns id, device_name, ip_address, trusted_at, expires_at, last_seen_at and is_current (the device whose cookie came with the request). It never exposes device_identifier or user_agent, and it reads through the repository, so it does not refresh last_seen_at the way isDeviceTrusted() does.
• Ownership: IUserTrustedDeviceRepository::getByIdAndUser() scopes the lookup by owner. Another user's device id is indistinguishable from a missing one (404), and the row is left untouched.
• Audit semantics (agreed on the ticket): device_revoked is logged only on a real false → true transition of is_revoked, one row per device.
  • Revoking an already revoked or expired device is a 204 no-op with no audit row.
  • Revoke-all logs one event per device it actually revokes, and none when there are no active devices.
• Cookie: when the revoked device is the current one, an expired device-trust cookie is queued with the same name, path, domain and flags as queueDeviceTrustCookie() (MFACookieManager::expireDeviceTrustCookie()), so the next login is challenged. The session itself stays active.
• removeTrustedDevices() now revokes active devices entity by entity inside a transaction and returns them. The old bulk revokeAllForUser() DQL UPDATE is removed; its only caller was this method, and it could not tell which devices it revoked.

Frontend

• New TrustedDevicesSection (resources/js/components/trusted_devices_section.js), mounted under the 2FA section of the profile page and shown only when twoFactorEnabled:
  • table with device, IP, trusted, last seen and expiry, plus a "This device" label;
  • a Revoke button per row that removes the row in place;
  • "Revoke all devices" behind a Swal confirmation, with a note that the current session stays active;
  • empty state when there are no devices.
• Buttons are plain onClick (the profile page is a single <form>).
• Endpoints exposed on window from profile.blade.php; fetch helpers in resources/js/profile/actions.js.

Deviations from the SDS / ticket

• Controller: the endpoints live in Api\UserApiController under users/me/2fa in routes/web.php, next to 2fa/enable and recovery-codes/regenerate, instead of the SDS's new Api\UserTwoFactorApiController in routes/api.php. This avoids splitting the same resource across two controllers.
• Unauthenticated calls return 302 to /auth/login, not 403: the group's auth middleware rejects guests before the controller runs, same as the sibling routes. The ticket's acceptance criterion was updated accordingly.
• Audit is written after the revocation commits (best-effort), not in the same transaction: ITwoFactorAuditService::log() opens its own transaction, and nesting DoctrineTransactionService::transaction() calls is unsafe (see RecoveryCodeService::enableTwoFactorAndGenerateCodes()). This follows the same pattern: an audit failure is logged as a warning and does not fail an already-committed revocation.
• Session flow key: the ticket's criterion says the next login lands on flow = mfa; the actual session value is 2fa, and that is what the test asserts.
• The SDS names the cookie fn_device_trust; the code keeps reading config('two_factor.cookie_name').

Testing

• tests/TrustedDevicesApiTest.php (new, 15 tests):
  • listing scope, field exposure, is_current and last_seen_at untouched;
  • single revoke with audit, plus the no-op revoke for revoked and for expired devices;
  • cross-user 404 and unknown id 404;
  • revoke-all with one audit row per device and zero when there are none;
  • cookie expired only for the current device;
  • a revoked device's old token is challenged again on password login;
  • unauthenticated 302 on all three routes.
• tests/DeviceTrustServiceTest.php: updated for the new removeTrustedDevices() behaviour; new unit tests for revokeTrustedDevice() and for surviving an audit failure.
• tests/TwoFactorProfileRoutesCsrfTest.php: both DELETE routes added.
• Jest: tests/js/components/trusted_devices_section.test.js (render, current-device label, empty state, revoke, failed revoke, revoke-all confirm/cancel, no submit buttons) and tests/js/profile/actions.test.js (the three helpers against the unmocked request layer).

Results:

• PHPUnit (MFA-related files only): all green, 16 files / 178 tests. DeviceTrustServiceTest, TrustedDevicesApiTest, TwoFactorProfileRoutesCsrfTest, TwoFactorRepositoriesTest, TwoFactorLoginFlowTest, RecoveryCodeRegenerationTest, OAuth2NativeMFALoginFlowTest, VerifyOTPChallengeTest, AuthServiceLoginUserTest and the tests/unit MFA / 2FA tests. The full PHPUnit suite was not run.
• Jest: yarn test:unit green, 13 suites / 76 tests.
• Webpack: production build compiles.
• The UI was not exercised manually in a browser.

Out of scope

2FA disable toggle and method selection, phone verification, admin-side device management, and friendly user-agent parsing for device_name.

Summary by CodeRabbit

• New Features
  • Added a Trusted Devices section to profiles with two-factor authentication, showing device details and identifying the current device.
  • Users can revoke a single trusted device or all trusted devices. Revoking devices leaves the current session active; revoked devices must complete verification at their next login.
• Bug Fixes
  • Revoking the current device clears its trusted-device status in the browser.
• Tests
  • Added coverage for device listings, revocation, login verification, and error handling.